Notes/Domino 6 and 7 Forum

Introduction

This document will help you ask better questions in the developerWorks Lotus forums, so that you can get better and faster answers. We want to help you solve your problems, and feel frustrated when we cannot. Please help us to help you.

The people with the knowledge to answer your questions are generally busy and don't have a lot of time to read the forums. This document will tell you:

• How to solve most problems on your own (which is generally the fastest way to get an answer).
• How to get the attention of the experts who know the answers.
• How to maintain good relations with these experts, so they are willing to help you.
• How to ensure that your question has enough information to let someone work on it.

Your helper might only check the forums once every couple of days, if that. The more they have to ask you questions, the longer it takes for you to get your answer.

How the Forums Work

These are user forums with voluntary participation. Nobody is paid to answer questions in the developerWorks forums.

There is nobody in IBM assigned to monitor these forums and make sure every question gets answered. Some IBMers do read these forums and answer questions, but it's not part of their jobs.

If you're in a big hurry, it's probably better not to post in the forums. If it's a support-related issue, call Lotus Support. If you just can't figure out how to make your application do what you need, you might consider hiring a consultant or looking for someone in your own organization who can help you.

Maintaining Good Relations with the Experts

You're more likely to get an answer to your question if you treat the other forum participants with respect and courtesy, and are considerate of their time. The people whose help you're asking for tend to be busy, and they like to use their time effectively and answer as many questions as they can.

• Read the Forum Use and Etiquette document. If you ignore the rules of the road, you are likely to get tickets from the etiquette police instead of answers.
• Bear in mind that we don't know how much you already know. You may get some suggestions that seem obvious or that seem to imply you don't know what you're doing. Many of the people who post don't know what they're doing, and we have no way to tell them apart from the ones who do.
• Search for answers before you post. We get really tired of seeing the same questions over and over (plus, you get an answer faster that way).
• Read the product documentation about the functions you're using.
• Try to solve the problem yourself before you ask for help. Make sure your post talks about what you've already tried.

How to Get the Attention of an Expert

A good subject line

When people scan the forums for questions to answer, they mostly look at the subject lines of the messages. If the subject doesn't tell them whether they probably know the answer, they're unlikely to read the message.

That's why it's a good idea to include some information about the topic of your question in the subject line. If it just says "Help" or "Urgent" or "How to do this?" you are not only providing no clue what your question is about, you're also proving that you didn't read the Forum Use and Etiquette document or this document.

Be complete and careful and specific

An expert is more likely to try to answer your question if you don't have any replies yet. If you do something that causes people to reply without answering your question (such as not following the etiquette guidelines, or asking a vague question that nobody understands), then other people who potentially might answer, may assume someone is already helping you.

Use the correct terminology

Sometimes people will search for questions in their special area of expertise by looking for certain keywords, e.g. "rich text". If your question is about rich text, then, be sure to use the words "rich text" in your message so that a search will find it. Using the right words also helps other people who are having the same problem later on, find your question and the answers to it.

Use the word CRISPY in the body of your post (NOT in the subject)

Some of the subject matter experts will first search for questions containing the word CRISPY. They will answer those questions first. This is how you get to the front of the queue.

Claiming that your question is CRISPY means that:

• you've read this document and followed its recommendations as best you are able.
• you've read the documentation, searched for answers, and tried to debug the problem yourself.
• you've thought about what information people might need to answer your question, and tried to provide that information up front.

How to Figure Out the Answer Yourself

• Read the manual about the functions you're using. Read the entire manual entry, including the usage notes. Look at the example code.
  • Can you use this function in the current context?
  • Have you provided legal values for all the parameters, of the correct datatypes?
  • Are you certain you actually know the values and datatypes of the parameters or operands? Use print statements, debugger, etc. to find out.
• TEST YOUR INPUTS. Often people say a particular function "doesn't work" when the real problem is that they passed it the wrong parameters. Use the debugger, or put output statements in your code, to make sure the variables have the values you think they do. Pay attention to the datatypes of parameters also. I know I'm repeating myself; that's because it is so often the problem that I want to make sure you don't miss it.
• Try to think of a test that will tell you the answer to your question. If there is one, do the test. That's generally faster and more reliable than hoping someone will tell you the answer.
• Search first in the forums, the Domino Designer help, and technotes, and your favorite internet search engine.
• Use the debugger and do whatever else you know how, to find out what's wrong and where it's happening. See here and here for diagnosis procedures. See below for other debugging suggestions.
• In LotusScript code always use Option Declare. Often, this will find the problem.
• Narrow down the cause of the problem. Reduce the code to the minimum necessary to reproduce the error. If you have a 300 line agent, try to create a 25 line agent that fails in the same way. Suppose you have a failure when looking up a document in a view. 50 lines of your code are involved in calculating the key value you use for the lookup. Delete all those lines and instead put in a constant key value (strKey = "G405 Rapid Transit") that you know is valid. If that fixes the problem, the issue is not with the lookup, but with the calculation of your key. Even if you don't solve the problem this way and you have to post a question, we are much more likely to bother to read a short piece of code than the original monster agent.
• If you have error handling in your code, temporarily remove the error handling (or have it display the error text and line number) so that if there's an error happening you can see what it is, rather than throw away that useful error message information. This applies to all programming languages.
• Look for places to do lower level tests. If a particular function fails, is it just that function, or is there a more basic problem? E.g. if a call to open database fails with an error: check whether the database exists, the network is active, you can connect with that server.
• Debug your code before you post. Even if there's not an error message. If you can tell exactly what's going wrong instead of guessing, then most of the time you'll see the answer yourself, and the rest of the time you'll have enough information to identify for sure which is the relevant part of the code. Look for anomalies, particularly in the values of variables. Find the exact line where something unexpected happens, even if it doesn't cause an error message. That's the important line. The problem was where you set a variable to the wrong value. The error message caused by using the variable might not happen until much later.
• If the error occurs on a complex statement, break the long statement it into smaller statements, using temporary variables if necessary, until you track down the exact function or operator that generates the error.

1. Use the subject line to say something about your problem. The subject is your best chance to get the attention of people who can help. We will read it if it looks like something we might know about. If it just says "help" or "urgent" or "LotusScript" or "date/time", that's not enough information to tell whether we might know the answer. The exact error message is a good thing to put in the subject line, or a brief description of the problem. Please, no "urgent", no "help", no ALL UPPERCASE.
2. Don't just say "it didn't work." What did it do, exactly, step by step? How is that different from what you expected?
3. Talk briefly about why you want to do this. You might be on the wrong track altogether, but people can't tell unless they know your destination.
4. The exact text of any error messages. Even if it's not in English. If it's not in English it's probably helpful to attempt a translation also, but we want the original text.
5. Be very specific. For instance, people might say, "DateDue is a date field." This is too vague. You know what you mean by this, but to us it could mean several very different things, e.g.
   • "DateDue is defined as type Date on my form."
   • "My agent assigns DateDue a date value with the statement 'doc.DateDue = Today'."
   • "I know DateDue contains a date value because I looked at the document properties from a view and here's the value it displays: 12/30/2004, with no quotes."
6. Say how you know what you know. This is really a continuation of the "be specific" point. Frequently people will say things in their post that turn out to be wrong -- the problem really isn't where they think it is. We need the facts, not just your conclusion, or we may be on a wild-goose chase.
7. Give full information about the context in which code runs. Is it in an agent, a form event (which one?), action button, input validation formula? Is this a Notes client application or a web application? Is it running in a dialogbox? Are you working on a document that's open in read mode? In edit mode? That was selected in a view? Is the database on a server, or is it a local replica? Is the code running in a server agent or in the Notes client?
8. Say what you've already tried. Because:
   • It shows you've put in some time yourself before asking for favors.
   • It helps people understand what you're trying to do, in case your question is ambiguous.
   • It prevents people from wasting your time suggesting what you've already tried.
9. What version of the product are you using? If there's a server and client involved, give information for both.
10. What operating system are you using on client and on server?
11. The relevant source code. Don't retype -- copy and paste the code. Not all your code. Just the part that's involved with the problem. If you don't know which code is relevant, see below.
12. Think a moment before you submit. Put yourself in our place. We know nothing about your issue except what you tell us. Have you really said enough for someone to understand your situation? Have you used unambiguous wording? Have you used the standard terminology (e.g. form vs. document)? Could you make things clearer or easier by providing a URL link to supporting information?
13. The word "Crispy" in the body of your post but not in the subject.

• The few lines leading up to the point where an error occurs are probably relevant.
• If the code is inside a loop, the entire loop is relevant.
• Declarations and earlier assignments of your variables, you should always include. Insert ellipsis (...) to show where you're leaving stuff out.
• It's okay to include some code you're not sure is important -- just not pages of code.